/*
 * Copyright 2010 Chad Retz
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package org.jdocng.parse;

import java.io.File;
import java.io.FileFilter;
import java.io.IOException;
import java.io.Reader;
import java.net.URL;

import org.jdocng.shared.Configuration;
import org.jdocng.shared.context.Context;
import org.jdocng.shared.model.Logger;

/**
 * Interface all parsers must implement
 *
 * @author Chad Retz
 */
public interface Parser {
    
    /**
     * Short name of this parser referenced when
     * loading via configuration value
     * 
     * @return
     */
    String getShortName();
    
    /**
     * Add a file to be parsed
     * 
     * @param file
     * @throws IOException
     */
    void addSource(File file) throws IOException;
    
    /**
     * Add a reader to be read
     * 
     * @param reader
     */
    void addSource(Reader reader);
    
    /**
     * Add a URL to a java file to the parser
     * 
     * @param url
     * @throws IOException
     */
    void addSource(URL url) throws IOException;
    
    /**
     * Add a directory to be parsed. By default this
     * loads all .java files beneath this directory
     * and its sub directories
     * 
     * @param directory
     * @throws IOException
     */
    void addDirectory(File directory) throws IOException;
    
    /**
     * Add a directory to be parsed using the given
     * file filter when recursively selecting files
     * 
     * @param directory
     * @param filter
     * @throws IOException
     */
    void addDirectory(File directory, FileFilter filter) throws IOException;
    
    /**
     * Parse all the previously added sources. There is no
     * need to use input directory values in the configuration
     * because that is handled and only what is needed is
     * added via other methods in this interface.
     * <p>
     * The resulting context simply needs all the classes, packages,
     * and types populated. The logger and configuration values
     * are set after this is retrieved.
     * 
     * @param configuration
     * @param logger
     * @return
     * @throws ParseException Any expected exception during parsing
     */
    Context parse(Configuration configuration, Logger logger) 
            throws ParseException;
}
